Chapter 6: continued

Addressing Objects

To retrieve or change the contents of the Frontier Object Database -- whether va a UserTalk script or manually -- you need a means of addressing objects in the database.

The basic method of addressing an object in Frontier is by supplying its full name, with each sub-table of which it is a member appearing in order from the root level down to the object, and each sub-table's name separated from the others by a period. Thus the sub-table called examples can be addressed as root.examples. An entry in that table called name would be addressed as examples.name. (Notice that we omit the "root" from the address. You never need to type "root" explicitly because Frontier always understands you to be addressing objects that have their ultimate home in the root table.)

If you type the address of a database object into the Quick Script window, Frontier will tell you that object's value. (Remember from above that the value of an object depends on the type of object and whether it is stored on disk or not.) For example, Figure 5-4 shows the results of typing root.examples into the Quick Script window. Since examples is a table, its value is the number of items it contains.

Figure 5-4. Typing an Object's Address Produces its Value

A complete understanding of addressing objects requires that we discuss several other subjects:

• omission of paths that are "known" to Frontier
• names containing special characters, such as spaces
• using an indexing method of addressing

When You Can Use Partial Object Names

Type the following line into the Quick Script window and execute it:

system.misc

You'll probably get an answer like "6 items" in the message area of the Quick Script window. This is hardly surprising. But now remove the first word of the address and type just "misc" into the Quick Script window. You'll get the same answer. (You might even want to be a real skeptic and change the previous contents of the message area by entering something like "2+2" into the Quick Script window between these two tests.) How does Frontier know where to find the object called misc if you don't tell it?

For the answer, type the following line into the Quick Script window and execute it:

edit (@misc.paths)

The result should look something like Figure 6-5. Examine this table and you'll quickly discover that it is a series of pre-defined paths to tables in the Frontier Object Database. Any object whose full name begins with any of these paths will be found if you supply only the remainder of its name (i.e., the part that would be appended to the end of one of these known paths).

Figure 6-5. Table of Pre-Defined Object Database Partial Paths

It is possible that two of these tables will contain an item that has the same name. Frontier searches this table from top to bottom, using the first match that it finds. For example, if there were two objects called misc, one in people.DGS and one in root.system, the one in the people table would essentially override the other unless a complete path to the latter was provided.

While you may add paths to this table, do so with caution. There are likely to be better ways to achieve whatever result you have in mind. (If you change the table and your scripts depend on the change, they will be harder to share with others.)

Names Containing Special Characters

In the table root.examples, there are three sample outlines that are used extensively in DocServer. They are called "Sample Outline 1," "Sample Outline 2," and "Sample Outline 3." If you try to type the name of one of these objects into the Quick Script window, an error condition will result.

Figure 5-5. Syntax Error from Using Multi-Word Object Name

If you click on the "Go To" button in this window to ask Frontier to take you to the place where the error occurs, you'll find the cursor flashing after the word "Outline." UserTalk sees this text as a script containing three consecutive table identifiers - "Sample", "Outline", and "1" - with no operators between them. This is an illegal script.

To access such objects in UserTalk, you must enclose the multi-word name in quotation marks and then you must enclose the entire quoted string in square brackets (see Figure 5-6).

Figure 5-6. Proper Syntax for Multi-Word Object Name

This syntax is actually a special case of the use of square brackets to force UserTalk to evaluate the expression contained between them and to use the result of that evaluation as an identifier (the name of a single table or cell). This somewhat advanced technique can be used to create generic scripts that would otherwise have to be customized for a particular user or configuration. For example, if you want a general purpose script that will refer to a value in the user's people table, you need to a way to include the user's initials. Frontier stores the initials at user.initials, the square brackets can evaluate (or "lookup") the value.

msg (people.[user.initials].favoriteColor)

As a reminder, the user's people table is global -- i.e. the exact path usually is not required. Unless there was another "favoriteColor" cell in a different "global" table, the following script is equivalent:

msg (favoriteColor)